package com.tbynet.jwp.repository.spi;

import com.tbynet.jwp.repository.dto.query.TermQuery;
import com.tbynet.jwp.repository.dto.result.TermResult;

import java.math.BigInteger;
import java.util.List;
import java.util.Map;

/**
 * 分类项查询仓储接口
 * 对应WordPress的术语（分类项）查询功能，包括获取分类项列表、详情等操作
 *
 * @author 佰亿互联
 * @version 1.0
 * @since 2025-11-04
 */
public interface _TermQueryRepository {

    /**
     * 根据分类项ID和分类法获取分类项详情
     * 对应WordPress：get_term函数
     *
     * @param termId 分类项ID
     * @param taxonomy 分类法类型
     * @return 分类项详情
     */
    TermResult getTermById(BigInteger termId, String taxonomy);

    /**
     * 根据分类项别名和分类法获取分类项详情
     * 对应WordPress：get_term_by('slug', ...)函数
     *
     * @param slug 分类项别名
     * @param taxonomy 分类法类型
     * @return 分类项详情
     */
    TermResult getTermBySlug(String slug, String taxonomy);

    /**
     * 根据分类项名称和分类法获取分类项详情
     * 对应WordPress：get_term_by('name', ...)函数
     *
     * @param name 分类项名称
     * @param taxonomy 分类法类型
     * @return 分类项详情
     */
    TermResult getTermByName(String name, String taxonomy);

    /**
     * 查询分类项列表
     * 对应WordPress：get_terms函数
     *
     * @param query 查询条件
     * @return 分类项列表
     */
    List<TermResult> listTerms(TermQuery query);

    /**
     * 分页查询分类项列表
     * 对应WordPress：get_terms函数（带分页参数）
     *
     * @param query 查询条件
     * @return 分页分类项列表
     */
    com.jfinal.plugin.activerecord.Page<TermResult> paginateTerms(TermQuery query);

    /**
     * 获取分类项的层级结构
     * 对应WordPress：get_terms函数（带层级参数）
     *
     * @param taxonomy 分类法类型
     * @param parentId 父级分类项ID
     * @return 层级分类项列表
     */
    List<TermResult> getTermHierarchy(String taxonomy, BigInteger parentId);

    /**
     * 根据文章ID获取分类项列表
     * 对应WordPress：wp_get_post_terms函数
     *
     * @param postId 文章ID
     * @param taxonomy 分类法类型
     * @return 分类项列表
     */
    List<TermResult> getTermsByPostId(BigInteger postId, String taxonomy);

    /**
     * 获取分类项元数据
     * 对应WordPress：get_term_meta函数
     *
     * @param termId 分类项ID
     * @param metaKey 元数据键（可选，为空则获取所有元数据）
     * @return 元数据值或元数据Map
     */
    Object getTermMeta(BigInteger termId, String metaKey);

    /**
     * 检查分类项是否存在
     * 对应WordPress：term_exists函数
     *
     * @param term 分类项标识（ID、名称或别名）
     * @param taxonomy 分类法类型
     * @return 存在返回分类项ID，不存在返回null
     */
    BigInteger termExists(Object term, String taxonomy);

    /**
     * 检查分类项别名是否存在
     * 对应WordPress：term_exists函数（slug检查）
     *
     * @param slug 分类项别名
     * @param taxonomy 分类法类型
     * @return 存在返回true，不存在返回false
     */
    boolean isSlugExists(String slug, String taxonomy);

    /**
     * 获取分类项数量
     * 对应WordPress：wp_count_terms函数
     *
     * @param taxonomy 分类法类型
     * @param query 查询条件
     * @return 分类项数量
     */
    Long countTerms(String taxonomy, TermQuery query);

    /**
     * 获取分类法统计信息
     * 对应WordPress：wp_count_terms函数（多个分类法）
     *
     * @param taxonomies 分类法类型列表
     * @return 分类法统计信息，key为分类法，value为数量
     */
    Map<String, Long> countTermsByTaxonomies(List<String> taxonomies);

    /**
     * 获取热门分类项（按文章数量排序）
     * 对应WordPress：get_terms函数（按count排序）
     *
     * @param taxonomy 分类法类型
     * @param limit 返回数量
     * @return 热门分类项列表
     */
    List<TermResult> getPopularTerms(String taxonomy, Integer limit);

    /**
     * 搜索分类项
     * 对应WordPress：get_terms函数（带搜索参数）
     *
     * @param keyword 搜索关键词
     * @param taxonomy 分类法类型
     * @param limit 返回数量
     * @return 搜索结果
     */
    List<TermResult> searchTerms(String keyword, String taxonomy, Integer limit);

    /**
     * 获取分类法信息
     * 对应WordPress：get_taxonomy函数
     *
     * @param taxonomy 分类法类型
     * @return 分类法信息
     */
    Map<String, Object> getTaxonomyInfo(String taxonomy);

    /**
     * 获取完整树形结构
     * 对应WordPress：get_terms函数（带层级参数）
     *
     * @param taxonomy 分类法类型
     * @return 完整树形结构
     */
    List<TermResult> getTermTree(String taxonomy);

    /**
     * 检查祖先关系
     * 对应WordPress：term_is_ancestor_of函数
     *
     * @param termId 分类项ID
     * @param ancestorId 祖先分类项ID
     * @param taxonomy 分类法类型
     * @return 是否是祖先关系
     */
    boolean isTermAncestor(BigInteger termId, BigInteger ancestorId, String taxonomy);

    /**
     * 获取默认分类项
     * 对应WordPress：get_default_category函数
     *
     * @param taxonomy 分类法类型
     * @return 默认分类项
     */
    TermResult getDefaultTerm(String taxonomy);

    /**
     * 获取分类项路径
     * 对应WordPress：get_term_parents_list函数
     *
     * @param termId 分类项ID
     * @param taxonomy 分类法类型
     * @return 分类项路径列表
     */
    List<TermResult> getTermPath(BigInteger termId, String taxonomy);

    /**
     * 获取同层级分类项
     * 对应WordPress自定义功能
     *
     * @param termId 分类项ID
     * @param taxonomy 分类法类型
     * @return 同层级分类项列表
     */
    List<TermResult> getSiblingTerms(BigInteger termId, String taxonomy);

    /**
     * 获取分类项深度
     * 对应WordPress自定义功能
     *
     * @param termId 分类项ID
     * @param taxonomy 分类法类型
     * @return 深度级别（0表示顶级）
     */
    Integer getTermDepth(BigInteger termId, String taxonomy);

    /**
     * 检查分类项是否为空
     * 对应WordPress：term_is_empty函数
     *
     * @param termId 分类项ID
     * @param taxonomy 分类法类型
     * @return 是否为空（没有关联文章）
     */
    boolean isTermEmpty(BigInteger termId, String taxonomy);

    /**
     * 获取分类项使用统计
     * 对应WordPress自定义功能
     *
     * @param taxonomy 分类法类型
     * @param days 统计天数
     * @return 使用统计信息
     */
    Map<String, Object> getTermUsageStatistics(String taxonomy, Integer days);

    /**
     * 获取最近更新的分类项
     * 对应WordPress自定义功能
     *
     * @param taxonomy 分类法类型
     * @param limit 返回数量
     * @return 最近更新的分类项列表
     */
    List<TermResult> getRecentlyUpdatedTerms(String taxonomy, Integer limit);

    /**
     * 验证分类项别名唯一性
     * 对应WordPress：wp_unique_term_slug函数
     *
     * @param slug 别名
     * @param taxonomy 分类法类型
     * @param excludeTermId 排除的分类项ID
     * @return 是否唯一
     */
    boolean isSlugUnique(String slug, String taxonomy, BigInteger excludeTermId);

    /**
     * 获取分类项关联的文章ID列表
     * 对应WordPress：get_objects_in_term函数
     *
     * @param termId 分类项ID
     * @param taxonomy 分类法类型
     * @return 关联的文章ID列表
     */
    List<BigInteger> getObjectsInTerm(BigInteger termId, String taxonomy);

    /**
     * 统计空分类项数量
     *
     * 统计指定分类法中没有关联任何文章的分类项数量，用于统计分析和系统监控
     *
     * @param taxonomy 分类法类型（如：category, post_tag）
     * @return Long 空分类项的数量，如果统计失败返回0L
     *
     * @example
     * <pre>{@code
     * // 统计空分类项数量
     * Long emptyCount = termQueryService.countEmptyTerms("category");
     * log.info("分类法 'category' 中有 {} 个空分类项", emptyCount);
     * }</pre>
     *
     * @since WordPress 4.9
     */
    Long countEmptyTerms(String taxonomy);

    /**
     * 查找未使用的分类项
     *
     * 查找指定分类法中没有关联任何文章的分类项，用于清理空分类项
     *
     * @param taxonomy 分类法类型（如：category, post_tag）
     * @return List<BigInteger> 未使用的分类项ID列表，如果没有找到返回空列表
     *
     * @example
     * <pre>{@code
     * // 查找未使用的分类项
     * List<BigInteger> unusedTermIds = termQueryService.findUnusedTerms("category");
     * if (!unusedTermIds.isEmpty()) {
     *     log.info("找到 {} 个未使用的分类项", unusedTermIds.size());
     * }
     * }</pre>
     *
     * @since WordPress 4.9
     */
    List<BigInteger> findUnusedTerms(String taxonomy);
}